Description
Overview
Included files
Included by
Source
/** \page "Documenting the code"
!!! Documenting the code
%Documenting code entities in DoxyS is generally done in front of the entity's declaration
(classes, typedef, defines, enums, variables, functions). For functions it's also
possible to put documentation at the definition in the CPP-file. }This is recommended
to keep header files compact and avoid recompiling more than necessary whenever one
changes the documentation.} It is also possible to put documentation in separate files,
see "Separate Docs" in the example code how to do this.
#Note:# Documenting eg. a function both in header- and cpp-file will cause DoxoS to
concatenate the documentation strings.
For variables, enum values and function parameters it is often easier to write the
usually short documentation }after} the entity on the same line instead of before.
This is both possible and recommended and is described later on this page. The
information presented here can also be found in a "by example form" in HowToDocument.
Here follows some examples of how to document entities. In the examples here we mostly
use the $/** ... \endds_doc$ and $/// ...$ styles when documenting, but as shown in the table
in Documenting::"Documentation blocks" it's also possible to use $/*! ... \endds_doc$ and $//! ... $.
! Documenting on same line as entity
By default a documetation block using fx. $/** ... \endds_doc$ contains documentation
for the entity immediately after. When documenting variables, enum values, function
parameters or any entity that needs just a very short documentation (like only a
brief description) it's often easier to place the doc string after the entity's
declaration using $/**< ... \endds_doc$ or $///< ...$. The next table will show some
examples of this also.
! Here are some quick examples:
| #Entity type# | #Syntax to use#
| class/struct || $/** Brief to newline or punctuation.\n... Description ...\endds_doc\n class HowToDocument\{\};$
| function || $/** Brief to newline or punctuation.\n... Description ...\n \\return ... return val description ...\endds_doc\n int HowToDocument::ReturnValue() \{\};$
| variable || $int m_iMemberVarShortDoc; ///< Short single line documentation.$
! About brief description
The brief description as generally shown in overview tables and mouse-over in the
output. It greatly enhances the the overview tables, provided the brief description
is }short} (just a single line/sentence) and }descriptive} for the entity. The brief
description ends at the first punctuation mark or newline, whicever comes first. This
is a little different from the original Doxygen, but that hopefully helps to ease
the writing of brief descriptions. In the rare cases you need a brief description to
span several lines refer to briefCmd.
!! Function parameter documentation
Function parameter documentation can be done either along with the declaration
using $/**< ... \endds_doc$ or $///< ...$ or in the functions general documentation
block using Java style command $\\param \ Param description$.\n
!Syntax:
\code
/**
Fun brief desc. ... more documentation...
void Fun( int iSize ///< Parameter documentation for iSize
)
{}
\endds_doc \endcode
The following functions in HowToDocument shows more variations:\n
- HowToDocument::Parameters
- HowToDocument::ParametersJavaStyle
- HowToDocument::ParametersTemplates
- HowToDocument::ParameterDocCombined
!! Enum values documentation
Works similar to parameters see HowToDocument::Enum for an example.
!Sytax:
\code
/**
Enumeration documentation. This must usually be done in the header file.
enum Enum { eEnumVal1 ///< eEnumVal1 enum #value# description.
};
\endds_doc \endcode
#Note:# This works also when the enumeration itself is anonymous.
!! Examples
See exampleCmd.
*/